home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat5 / cpuset.z / cpuset
Encoding:
Text File  |  2001-04-17  |  14.9 KB  |  331 lines
  1.  
  2.  
  3.  
  4. ccccppppuuuusssseeeetttt((((5555))))                                                            ccccppppuuuusssseeeetttt((((5555))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      cpuset - overview of cpusets
  10.  
  11. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  12.      A cpuset is a named set of CPUs, which may be defined to be restricted or
  13.      open.  A restricted cpuset only allows processes that are members of the
  14.      cpuset to run on the set of CPUs.  An open cpuset allows any process to
  15.      run on its cpus, but a process that is a member of the cpuset can only
  16.      run on the CPUs belonging to the cpuset.
  17.  
  18.      A principal use of cpusets is to create a partition of CPUs within a
  19.      larger system.  By doing this, a set of processes can be contained to
  20.      specific CPUs, reducing the amount of interaction those processes have
  21.      with other work on the system.  In the case of a restricted cpuset, the
  22.      processes that are attached to that cpuset will not be affected by other
  23.      work on the system; only those processes attached to the cpuset can be
  24.      scheduled to run on the CPUs assigned to the cpuset.  An open cpuset can
  25.      be used to restrict processes to a set of CPUs so that the affect these
  26.      processes have on the rest of the system is minimized.
  27.  
  28.      There are currently two methods in which to use cpusets: the _cccc_pppp_uuuu_ssss_eeee_tttt(1)
  29.      command, and the cpuset library (see THE CPUSET LIBRARY section below).
  30.  
  31.      For information on how to use cpusets in a Trusted IRIX environment, see
  32.      the _cccc_pppp_uuuu_ssss_eeee_tttt(1) man page.
  33.  
  34. TTTTHHHHEEEE CCCCPPPPUUUUSSSSEEEETTTT CCCCOOOOMMMMMMMMAAAANNNNDDDD
  35.      The _cccc_pppp_uuuu_ssss_eeee_tttt command is used to create and destroy cpusets, to retrieve
  36.      information about existing cpusets, and to attach a process and all of
  37.      its children to a cpuset.
  38.  
  39.      The _cccc_pppp_uuuu_ssss_eeee_tttt command uses a cpuset configuration file and a name (see
  40.      _cccc_pppp_uuuu_ssss_eeee_tttt(4) for a definition of the file format).  The cpuset configuration
  41.      file is used to define the CPUs that are members of the cpuset.  It also
  42.      contains additional parameters required to define the cpuset.  A cpuset
  43.      name is between three and eight characters long; names of two or less
  44.      characters are reserved.
  45.  
  46.      The file permissions of the configuration file define access to the
  47.      cpuset.  When permissions need to be checked, the current permissions of
  48.      the file are used.  It is therefore possible to change access to a
  49.      particular cpuset without having to tear it down and recreate it, simply
  50.      by changing the access permissions.  Read access allows a user to
  51.      retrieve information about a cpuset while execute permission allows the
  52.      user to attach a process to the cpuset.
  53.  
  54.      For additional information concerning the _cccc_pppp_uuuu_ssss_eeee_tttt command, consult the
  55.      _cccc_pppp_uuuu_ssss_eeee_tttt(1) manual page.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ccccppppuuuusssseeeetttt((((5555))))                                                            ccccppppuuuusssseeeetttt((((5555))))
  71.  
  72.  
  73.  
  74. THE CPUSET LIBRARY
  75.      The cpuset library provides interfaces that allow a programmer to create
  76.      and destroy cpusets, retrieve information about existing cpusets, and to
  77.      attach a process and all of its children to a cpuset.
  78.  
  79.      The cpuset library requires that a permission file be defined for a
  80.      cpuset that is created.  The permissions file may be an empty file, since
  81.      it is only the file permissions for the file that define access to the
  82.      cpuset.  When permissions need to be checked, the current permissions of
  83.      the file are used.  It is therefore possible to change access to a
  84.      particular cpuset without having to tear it down and recreate it, simply
  85.      by changing the access permissions.  Read access allows a user to
  86.      retrieve information about a cpuset while execute permission allows the
  87.      user to attach a process to the cpuset.
  88.  
  89.      The cpuset library is provided as a N32 DSO library.  The library file is
  90.      _llll_iiii_bbbb_cccc_pppp_uuuu_ssss_eeee_tttt_...._ssss_oooo, and it is normally located in the directory _////_llll_iiii_bbbb_3333_2222.  Users
  91.      of the library must include the _cccc_pppp_uuuu_ssss_eeee_tttt_...._hhhh header file which is located in
  92.      _////_uuuu_ssss_rrrr_////_iiii_nnnn_cccc_llll_uuuu_dddd_eeee.  The function interfaces provided in the cpuset library are
  93.      declared as optional interfaces to allow for backwards compatability as
  94.      new interfaces are added to the library.  This library is only available
  95.      on IRIX 6.5.8 and later versions.
  96.  
  97.      It is possible to compile and run a program that uses this DSO and its
  98.      interfaces if they are available, but continues to execute if they are
  99.      missing. To do this, a replacement library for _llll_iiii_bbbb_cccc_pppp_uuuu_ssss_eeee_tttt_...._ssss_oooo must be
  100.      created.  An example of how to create a replacement library is provided
  101.      in the EXAMPLES section.
  102.  
  103.      The function interfaces within the cpuset library include:
  104.  
  105.      _cccc_pppp_uuuu_ssss_eeee_tttt_CCCC_rrrr_eeee_aaaa_tttt_eeee(3x)
  106.           Create a cpuset
  107.  
  108.      _cccc_pppp_uuuu_ssss_eeee_tttt_AAAA_tttt_tttt_aaaa_cccc_hhhh(3x)
  109.           Attach the current process to a cpuset
  110.  
  111.      _cccc_pppp_uuuu_ssss_eeee_tttt_DDDD_eeee_tttt_aaaa_cccc_hhhh_AAAA_llll_llll(3x)
  112.           Detach all threads from a cpuset
  113.  
  114.      _cccc_pppp_uuuu_ssss_eeee_tttt_DDDD_eeee_ssss_tttt_rrrr_oooo_yyyy(3x)
  115.           Destroy a cpuset
  116.  
  117.      _cccc_pppp_uuuu_ssss_eeee_tttt_GGGG_eeee_tttt_CCCC_PPPP_UUUU_CCCC_oooo_uuuu_nnnn_tttt(3x)
  118.           Obtain the number of CPUs configured on the system
  119.  
  120.      _cccc_pppp_uuuu_ssss_eeee_tttt_GGGG_eeee_tttt_CCCC_PPPP_UUUU_LLLL_iiii_ssss_tttt(3x)
  121.           Get the list of all CPUs assigned to a cpuset
  122.  
  123.      _cccc_pppp_uuuu_ssss_eeee_tttt_GGGG_eeee_tttt_NNNN_aaaa_mmmm_eeee(3x)
  124.           Get the name of the cpuset to which a process is attached
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ccccppppuuuusssseeeetttt((((5555))))                                                            ccccppppuuuusssseeeetttt((((5555))))
  137.  
  138.  
  139.  
  140.      _cccc_pppp_uuuu_ssss_eeee_tttt_GGGG_eeee_tttt_NNNN_aaaa_mmmm_eeee_LLLL_iiii_ssss_tttt(3x)
  141.           Get a list names for all defined cpusets
  142.  
  143.      _cccc_pppp_uuuu_ssss_eeee_tttt_GGGG_eeee_tttt_PPPP_IIII_DDDD_LLLL_iiii_ssss_tttt(3x)
  144.           Get a list of all PIDs attached to a cpuset
  145.  
  146.      _cccc_pppp_uuuu_ssss_eeee_tttt_AAAA_llll_llll_oooo_cccc_QQQQ_uuuu_eeee_uuuu_eeee_DDDD_eeee_ffff(3x)
  147.           Allocate a cpuset_QueueDef_t structure
  148.  
  149.      _cccc_pppp_uuuu_ssss_eeee_tttt_FFFF_rrrr_eeee_eeee_QQQQ_uuuu_eeee_uuuu_eeee_DDDD_eeee_ffff(3x)
  150.           Release memory used by a cpuset_QueueDef_t structure
  151.  
  152.      _cccc_pppp_uuuu_ssss_eeee_tttt_FFFF_rrrr_eeee_eeee_CCCC_PPPP_UUUU_LLLL_iiii_ssss_tttt(3x)
  153.           Release memory used by a cpuset_CPUList_t structure
  154.  
  155.      _cccc_pppp_uuuu_ssss_eeee_tttt_FFFF_rrrr_eeee_eeee_NNNN_aaaa_mmmm_eeee_LLLL_iiii_ssss_tttt(3x)
  156.           Release memory used by a cpuset_NameList_t structure
  157.  
  158.      _cccc_pppp_uuuu_ssss_eeee_tttt_FFFF_rrrr_eeee_eeee_PPPP_IIII_DDDD_LLLL_iiii_ssss_tttt(3x)
  159.           Release memory used by a cpuset_PIDList_t structure
  160.  
  161. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  162.      This example creates a cpuset named "myqueue" containing CPUs 4, 8, and
  163.      12.  The example uses the interfaces in the cpuset library,
  164.      _////_llll_iiii_bbbb_3333_2222_////_llll_iiii_bbbb_cccc_pppp_uuuu_ssss_eeee_tttt_...._ssss_oooo, if they are present.  If the interfaces are not
  165.      present, it attempts to use the _c_p_u_s_e_t(1) command to create the cpuset.
  166.  
  167.                #include <cpuset.h>
  168.                #include <stdio.h>
  169.                #include <errno.h>
  170.  
  171.                #define PERMFILE "/usr/tmp/permfile"
  172.  
  173.                int
  174.                main(int argc, char **argv)
  175.                {
  176.                    cpuset_QueueDef_t *qdef;
  177.                    char              *qname = "myqueue";
  178.                    FILE              *fp;
  179.  
  180.                    /* Alloc queue def for 3 CPU IDs */
  181.                    if (_MIPS_SYMBOL_PRESENT(cpusetAllocQueueDef)) {
  182.                        printf("Creating cpuset definition\n");
  183.                        qdef = cpusetAllocQueueDef(3);
  184.                        if (!qdef) {
  185.                            perror("cpusetAllocQueueDef");
  186.                            exit(1);
  187.                        }
  188.  
  189.                        /* Define attributes of the cpuset */
  190.                        qdef->flags = CPUSET_CPU_EXCLUSIVE
  191.                                    | CPUSET_MEMORY_LOCAL
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ccccppppuuuusssseeeetttt((((5555))))                                                            ccccppppuuuusssseeeetttt((((5555))))
  203.  
  204.  
  205.  
  206.                                    | CPUSET_MEMORY_EXCLUSIVE;
  207.                        qdef->permfile = PERMFILE;
  208.                        qdef->cpu->count = 3;
  209.                        qdef->cpu->list[0] = 4;
  210.                        qdef->cpu->list[1] = 8;
  211.                        qdef->cpu->list[2] = 12;
  212.                    } else {
  213.                        printf("Writing cpuset command config"
  214.                                " info into %s\n", PERMFILE);
  215.                        fp = fopen(PERMFILE, "a");
  216.                        if (!fp) {
  217.                            perror("fopen");
  218.                            exit(1);
  219.                        }
  220.                        fprintf(fp, "EXCLUSIVE\n");
  221.                        fprintf(fp, "MEMORY_LOCAL\n");
  222.                        fprintf(fp, "MEMORY_EXCLUSIVE\n\n");
  223.                        fprintf(fp, "CPU 4\n");
  224.                        fprintf(fp, "CPU 8\n");
  225.                        fprintf(fp, "CPU 12\n");
  226.                        fclose(fp);
  227.                    }
  228.  
  229.                    /* Request that the cpuset be created */
  230.                    if (_MIPS_SYMBOL_PRESENT(cpusetCreate)) {
  231.                        printf("Creating cpuset = %s\n", qname);
  232.                        if (!cpusetCreate(qname, qdef)) {
  233.                            perror("cpusetCreate");
  234.                            exit(1);
  235.                        }
  236.                    } else {
  237.                        char command[256];
  238.  
  239.                        fprintf(command, "/usr/sbin/cpuset -q %s -c"
  240.                               "-f %s", qname,
  241.                               PERMFILE);
  242.                        if (system(command) < 0) {
  243.                            perror("system");
  244.                            exit(1);
  245.                        }
  246.                    }
  247.  
  248.                    /* Free memory for queue def */
  249.                    if (_MIPS_SYMBOL_PRESENT(cpusetFreeQueueDef)) {
  250.                        printf("Finished with cpuset definition,"
  251.                                " releasing memory\n");
  252.                        cpusetFreeQueueDef(qdef);
  253.                    }
  254.  
  255.                    return 0;
  256.                }
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. ccccppppuuuusssseeeetttt((((5555))))                                                            ccccppppuuuusssseeeetttt((((5555))))
  269.  
  270.  
  271.  
  272.      This example shows how to create a replacement library for
  273.      _////_llll_iiii_bbbb_3333_2222_////_llll_iiii_bbbb_cccc_pppp_uuuu_ssss_eeee_tttt_...._ssss_oooo so that a program built to use the cpuset library
  274.      interfaces will execute if the library is not present.
  275.  
  276.        1. The file replace.c is created, and contains the following line of
  277.        code:
  278.  
  279.                  static void cpusetNULL(void) { }
  280.  
  281.  
  282.        2. The file replace.c is compiled:
  283.  
  284.                  cc -mips3 -n32 -c replace.c
  285.  
  286.  
  287.        3. The object replace.o created in the previous step is placed in a
  288.        library:
  289.  
  290.                  ar ccrl libcpuset.a replace.o
  291.  
  292.  
  293.        4. The library is converted into a DSO:
  294.  
  295.                  ld -mips3 -n32 -quickstart_info -nostdlib        \
  296.                      -elf -shared -all -soname libcpuset.so       \
  297.                      -no_unresolved -quickstart_info -set_version \
  298.                      sgi1.0 libcpuset.a -o libcpuset.so
  299.  
  300.  
  301.        5. The DSO is installed on the system:
  302.  
  303.                  install -F /opt/lib32 -m 444 -src libcpuset.so \
  304.                      libcpuset.so
  305.  
  306.  
  307.      The replacement library can be installed in a directory defined by the
  308.      LD_LIBRARYN32_PATH environment variable (see _r_l_d(1)).  If the replacement
  309.      library must be installed in a directory that is in the default search
  310.      path for shared libraries, it should be installed in _////_oooo_pppp_tttt_////_llll_iiii_bbbb_3333_2222.
  311.  
  312. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  313.      cpuset(1), cpuset(4), cpusetAllocQueueDef(3x), cpusetAttach(3x),
  314.      cpusetCreate(3x), cpusetDestroy(3x), cpusetDetachAll(3x),
  315.      cpusetFreeCPUList(3x), cpusetFreeNameList(3x), cpusetFreePIDList(3x),
  316.      cpusetGetCPUCount(3x), cpusetGetCPUList(3x), cpusetGetName(3x),
  317.      cpusetGetNameList(3x), cpusetGetPIDList(3x).
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.